<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Labels</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Labels</h1>
<p>A label identifies a line of code, and can be used as a <a href="../commands/Goto.htm">Goto</a> target or to form a <a href="../commands/Gosub.htm">subroutine</a>.</p>
<pre class="Syntax">LabelName:</pre>
<p>To create a label, write the label name followed by a colon as shown above. Aside from whitespace and comments, no other code can be written on the same line.</p>
<p><strong>Names:</strong> Label names are not case sensitive, and may consist of any characters other than space, tab, comma and the <a href="../commands/_EscapeChar.htm">escape character</a> (`). However, due to style conventions, it is generally better to use only letters, numbers, and the underscore character (for example: <em>MyListView</em>, <em>Menu_File_Open</em>, and <em>outer_loop</em>). Label names must be unique throughout the whole script.</p>
<p>Although there are no reserved names, it is strongly recommended that the following names not be used: On, Off, Toggle, AltTab, ShiftAltTab, AltTabAndMenu and AltTabMenuDismiss. These values have special meaning to the <a href="../commands/Hotkey.htm">Hotkey command</a>.</p>
<p><strong>Target:</strong> The target of a label is the next line of executable code. Executable code includes commands, assignments, <a href="../Variables.htm#Expressions">expressions</a> and <a href="../commands/Block.htm">blocks</a>, but not directives, labels, hotkeys or hotstrings. In the following example, <code>run_notepad</code> and <code>#n</code> both point at the <code>Run</code> line:</p>
<pre>run_notepad:
#n::
    Run Notepad
    return
</pre>
<p><strong>Execution:</strong> Like directives, labels have no effect when reached during normal execution. In the following example, a message box is shown twice - once during execution of the subroutine by <a href="../commands/Gosub.htm">Gosub</a>, and again after the subroutine returns:</p>
<pre>gosub Label1

Label1:
MsgBox <a href="../Variables.htm#ThisLabel">%A_ThisLabel%</a>
return</pre>

<h2>Subroutines</h2>
<p>A subroutine is a portion of code which can be <em>called</em> to perform a specific task. Execution of a subroutine begins at the target of a label and continues until a <a href="../commands/Return.htm">Return</a> or <a href="../commands/Exit.htm">Exit</a> is encountered. Since the end of a subroutine depends on flow of control, any label can act as both a Goto target and the beginning of a subroutine.</p>

<h2>Dynamic Labels</h2>
<p>Many commands which accept a label name also accept a <a href="../Variables.htm">variable</a> reference such as %MyLabel%, in which case the name stored in the variable is used as the target. However, performance is slightly reduced because the target label must be &quot;looked up&quot; each time rather than only once when the script is first loaded.</p>

<h2>Hotkeys and Hotstrings</h2>
<p><a href="../Hotkeys.htm">Hotkey</a> and <a href="../Hotstrings.htm#label">hotstring labels</a> are also valid targets for <a href="../commands/Goto.htm">Goto</a>, <a href="../commands/Gosub.htm">Gosub</a> and other commands. However, if a hotkey or hotstring has multiple <a href="../commands/_IfWinActive.htm">variants</a>, the variant closest to the top of the script is used. All of the hotkey's modifiers or hotstring's options are also part of its label name, but the final double-colon (::) is omitted.</p>

<h2>Named Loops</h2>
<p>A label can also be used to identify a loop for the <a href="../commands/Continue.htm">Continue</a> and <a href="../commands/Break.htm">Break</a> commands. This allows the script to easily continue or break out of any number of nested loops.</p>

<h2 id="Functions">Functions</h2>
<p>In <span class="ver">[v1.1.20]</span> and later, <a href="../Functions.htm">functions</a> can be used in place of labels in a number of cases, including:</p>
<ul>
  <li><a href="../commands/Gui.htm#Labels">Gui events</a> such as GuiClose</li>
  <li><a href="../commands/Gui.htm#label">Gui control events</a> (g-labels)</li>
  <li><a href="../commands/Hotkey.htm#Functor">Hotkey</a></li>
  <li><a href="../commands/Menu.htm#Functor">Menu</a></li>
  <li><a href="../commands/SetTimer.htm#Functor">SetTimer</a></li>
</ul>
<p></p>
<p>The benefits of functions are that they can use local variables, and in some cases (such as Gui control events) they also accept parameters containing useful information.</p>

<h2>Related</h2>
<p><a href="../Functions.htm#IsLabel">IsLabel()</a>, <a href="../Variables.htm#ThisLabel">A_ThisLabel</a>, <a href="../commands/Gosub.htm">Gosub</a>, <a href="../commands/Goto.htm">Goto</a>, <a href="../commands/OnExit.htm">OnExit</a>, <a href="../commands/SetTimer.htm">SetTimer</a>, <a href="../commands/Hotkey.htm">Hotkey</a>, <a href="../commands/Gui.htm#Labels">Gui Events</a>, <a href="../commands/Gui.htm#label">g-label</a>, <a href="../commands/OnClipboardChange.htm">OnClipboardChange</a></p>

</body>
</html>
